◊ This control panel is distributed as shareware: if you like it please honor the shareware system by sending $10 to the author at the address above. Since cashing international cheques is very expensive, please send cash only (U.S. dollars are best, but any other currency is fine).
◊ If you work on the Macintosh, there are many things you can send me instead of the money. Here are some suggestions: original software (but don't send any shareware/freeware unless you're the author), books or computer-related magazines (any free issue or subscription is welcome), CD-ROMs, any piece of new or used hardware, or anything else you've created.
◊ There's still another thing you could do: I'll finish my physics studies sometime in 1996 and I'm looking for a one-year job as a programmer (or maybe a scientist?) outside of Italy. Let me know if you have anything to offer.
◊ If you can't afford any of the above an e-mail, a postcard or a letter is welcome. I speak English, French and Italian. Please forgive me if I don't answer to all of your letters - I am often overloaded with my school work.
• Special offers
◊ The following people may register at a special price and pay $5 instead of $10:
- all registered users of any of my other shareware programs (that is, anyone who already sent me something);
- all high-school and college students;
- anyone else who is under 25.
◊ You may want to get a copy of the complete ShareDisk package, which contains all my shareware programs (more than 35 utilities, including KeyQuencer, for an overall value of over $100) and can be registered for only $25. The ShareDisk is available as a one-megabyte compressed archive and can be downloaded from my ftp server.
• Introduction
◊ KeyQuencer is a very useful control panel that lets you perform complex tasks with one keystroke. I wrote it because I wasn’t satisfied with the commercial macro engines currently available, as they require lots and lots of memory and often fill it with less than useful stuff. KeyQuencer uses a scripting approach; it can’t watch your steps to learn new sequences as other commercial packages do. This requires a bit more work when you define a new sequence, but the final impact of KeyQuencer on your system is a lot smaller in terms of memory usage and processor time.
◊ KeyQuencer works with special structures called macros, which are defined by a name, a key combination and a text. The macro name only appears in the control panel; it allows you to pick the right macro for editing or deletion and to have an easily readable list of all your macros (you can also copy the list to a text editor and print it). The macro key is the key combination you use to activate the macro: when KeyQuencer detects a macro key, it starts executing the macro without stopping the applications you’re using. The actual task performed by the macro is defined by the macro text, which is a sequence of simple instructions. KeyQuencer has no built-in instructions; all the instructions are kept in separate external files called extensions. This allows you to leave unused extensions out of your Mac’s memory and to add more extensions as they become available.
• Installation
◊ System 7: Move the KeyQuencer control panel into your Control Panels folder (inside the System folder). Move the KeyQuencer Extensions folder into any one of the Preferences, Extensions, Control Panels or System folders. Move the KQ Apple Events extension into the Extensions folder if you want to call KeyQuencer macros from AppleScript or if you plan to use the "OMOpen" extension. Restart your Macintosh, then open the Control Panels folder and double click on KeyQuencer’s icon to configure it.
◊ System 6: Move the KeyQuencer control panel and the KeyQuencer Extensions folder inside your System folder. Restart your Macintosh, then open the Control Panel desk accessory to configure it. The KQ Apple Events extension doesn’t work with system 6, and you won’t be able to use the "Open" and "Quit" commands.
◊ Macro Editor: The Macro Editor application works with both system 6 and 7; you may keep it anywhere you like on your disk.
◊ Japanese and other non-roman systems: Don’t forget to enable the WorldScript II work-around in the Preferences dialog (the work-around is installed at next restart).
• Special Keystrokes
◊ KeyQuencer provides two special keystrokes that may not be changed or assigned to a macro:
- Cmd-Shift-Return stops any running macro and flushes the macro queue.
- Cmd-Shift-Option-Return toggles KeyQuencer on and off on the fly. You'll see many short flashes of the activity monitor when you turn KeyQuencer on, and one long flash when you turn it off.
• The control panel
◊ The KeyQuencer control panel allows you to view and edit macros and to assign them a keystroke. The following commands are available in the control panel’s fake menu bar:
◊ New Macro…: Creates a new macro and brings up the macro editor window.
◊ Edit Macro…: Brings up the macro editor for the first selected macro (the first one that is highlighted in the macro list). You can use cmd-return instead of enter to press the “OK” button in the editor. Does nothing if no macro is selected.
◊ Delete Macro(s): Deletes all selected macros after asking if it’s OK to do so. This operation cannot be undone, whereas cutting the macros via the Edit menu leaves them in the clipboard. Does nothing if no macro is selected.
◊ Preferences…: Displays the preferences dialog. You may choose whether to display the key combinations in the list or not; when visible, the key combinations may be displayed graphically, as right-aligned text or just appended to the macro name. The activity monitor is a red square that gets drawn in the menu bar when a macro is running; you can turn it off if it bugs you. You may also turn the startup icon on and off. The last two options deal with special workarounds I made for Microsoft Word’s nonstandard implementation of the Macintosh event loop and for Apple’s own WorldScript II. KeyQuencer doesn’t work in Word if the first workaround is disabled, while the second is useful when working with non-roman script systems such as Japanese.
◊ Import Macros…: Imports all the macros contained in a previously exported macro file or in another KeyQuencer control panel. If duplicate names are found for some macros, you’ll be asked whether you want to skip them.
◊ Export Selected…: Exports the currently selected macros to an external macro file, so you can save them for later use or for distribution. Does nothing if no macro is selected.
◊ Edit Menu: All the Edit menu commands work as expected.
◊ About KeyQuencer…: Displays this text and lets you save it as a text file. You may also save a text file with your personal registration form.
◊ Save Registration Form…: Asks you to enter you name and address and saves a text file with your personal registration form, which can be printed with TeachText or any other text editor.
◊ Keyboard Shortcuts…: Displays all control panel shortcuts. KeyQuencer can’t assign command keys to its menu commands because it is not an application, so the shortcuts are implemented through the shift key.
◊ Memory Usage…: This tells you exactly how much of your Mac’s memory is being used by KeyQuencer. A full working setup with all the extensions installed and lots of macros typically requires less than 100K. The KQ Apple Events extension, which is a background-only application designed to support AppleScript and Apple Events, takes another 16K if it’s installed.
◊ The macro list displays all currently defined macros in alphabetical order. You may double click on a macro to edit it (same as the Edit Macro command). Holding down the shift or command key when clicking in the list lets you select more than one macro at a time; multiple selections are useful for the Export and Delete commands described above.
◊ The on/off master switch enables or disables KeyQuencer.
• The Macro Editor application
◊ The Macro Editor is a simple text editor with some extra features that allow it to cooperate with KeyQuencer either locally or over a network. You can save macros as plain text files and store them anywhere you like (including handy places like the “Startup Items” and “Apple Menu” folders); double-clicking a text macro file or dropping it onto the Macro Editor’s icon launches the macro it contains. The Macro Editor can quit automatically after it has executed your macro if you don’t want it to hang around.
◊ The try macro command lets you execute a macro on the fly, without going to the control panel or assigning it to a particular keystroke. This makes it a lot easier to test new macros, even though you’ll have to begin them with a SwitchApp command if they are intended to work on top of a specific application.
◊ The insert pathname command is useful with commands like Open, so you don’t have to remember the names of all your files and folders.
◊ The extensions menu works much like the command and parameter lists in the control panel’s macro editor; you may use it to quickly build a macro with very little typing. Since building the menu takes a while, you may want to leave the menu empty at launch and build it later when you need it.
◊ The help window gathers information about all the currently installed KeyQuencer extensions; you can save the text and print it with a text editor to create a quick reference for all of KeyQuencer’s commands. The help window is only available after the Extensions menu has been built.
◊ The remote menu allows you to send macros to other Macs on a network. This requires both KQ Apple Events running and Program Linking enabled on the target machine. You may attach the current target to a text macro file to have the macro automatically sent to the target when you open it with the Macro Editor. The attached target can be later removed or inspected. Note that it is impossible to send macros over the network from outside the Macro Editor, since a full application is required to support program linking. The Send Clipboard Text command can be used to send the current clipboard text to a remote Macro Editor application; you may transfer a macro from one computer to another without using file sharing by copying the text, choosing a remote Macro Editor application as the target and then sending the clipboard text to it; you can then use the paste command in the remote application to insert the text in a new macro.
◊ The Macro Editor is also available as a fat application (with native PowerPC code). The fat version is not much faster because it doesn’t do any number crunching and because most of the toolbox routines it uses are not native yet. Since the fat version is twice as big as the 68K application, it is distributed as a separate file.
• Shortcuts
◊ Typing some characters when the control panel is open selects the first macro in the list whose name matches the characters typed. You should not use the shift key while typing because it is used as a command key replacement for KeyQuencer’s menus.
◊ Some keys may be used as shortcuts when KeyQuencer’s control panel is the front window. Some have to be typed alone, others need the shift key; I could not use the command key because the Finder doesn’t let control panels use it.
- shift-N = New macro
- shift-E = Edit macro
- shift-D or backspace = Delete macro(s)
- shift-I = Import macros
- shift-X = eXport macros
- shift-P = Preferences
- shift-A = select All
- shift-S, return or enter = Select none
- down arrow, right arrow or tab key = select next macro
- up arrow, left arrow or shift-tab = select previous macro
• Cut and paste
◊ The standard Edit menu commands work fine in KeyQuencer’s control panel. You may use the Scrapbook desk accessory to store your macros for later use (you'll be able to see the macro names there). Exporting to an external file is more convenient if you want to move your macros from one Mac to another.
◊ You can print a list of your macros by selecting them all in the control panel, copying them and pasting the list into your favourite text editor.
• Known limitations and future improvements
◊ All key assignments are global; there is no way to let a keystroke “flow” through a macro once it’s been intercepted by KeyQuencer. This means you shouldn’t assign any keystroke that is meaningful to your applications, since you wouldn’t be able to have it act as usual when needed. This is unlikely to change in future versions because of the way KeyQuencer works; I had to write it this way to keep it as clean and compatible as I could. The only advantage is that you can’t mess up by calling the wrong macro when you switch from one application to another. If many of you really miss this feature then I’ll try to think about it.
◊ There are a couple of things that still didn’t make it into this release. These limitations will eventually be addressed in future versions, especially if many (registered) users complain about them.
- Macros defined in the control panel can’t have more than 255 characters (you can execute longer macros with the Macro Editor application, with the Open macro command or from HyperCard and AppleScript; this limitation only affects the control panel macro editor). Worse yet, the control panel doesn’t inform you when your macro is too long- it just chops it.
- There is no way to display a quick reference of all the key assignments; you have to open the control panel when you forget your keys (here’s a cool macro to do it: SwitchApp "Finder", then Open panels "KeyQuencer").
- The menu bar activity monitor is ugly (even though it’s very compatible). I’ll try to transmogrify it into a cool small icon if you really can’t stand the good ol’ red square.
- The control panel doesn’t have a separate preferences file, so you have to manually export your macros if you don’t want to lose them when you trash the control panel itself (be careful - this will surely happen when you upgrade to a newer version).
◊ KeyQuencer doesn’t have a timer, but it comes with a link that allows you to execute KeyQuencer macros with Chris Johnson’s Cron timer (available at ftp://ftp.cc.utexas.edu/pub/chrisj).
◊ Desk accessories intercept keystrokes before KeyQuencer; this isn’t usually a problem because most desk accessories don’t handle weird keystrokes (some beep, others don’t do anything at all). KeyQuencer handles the keystroke as soon as it comes out of the desk accessory. I didn’t fix this unusual behaviour because doing so required some more patches, but I may take care of it in the future if someone finds it annoying.
◊ Changes made in the control panel take effect immediately under System 6.0.4 or later; those who use an older system must restart the Mac for the macros and the preferences to be updated. Also, I haven’t done much testing on these older systems.
• Writing extensions for KeyQuencer
◊ Programmers may wish to add their own extensions to KeyQuencer. This release comes with a developer’s toolkit that contains everything you need to write an extension in C; sample code for a working extension is also included along with Think C 7.0 and Code Warrior projects. The current interface will still work with future releases of KeyQuencer.
◊ Please send me a copy of your extensions. I’ll be happy to test them and to send you beta releases of KeyQuencer if they have new features that may help you.
◊ You may find the latest version of all my shareware programs by anonymous ftp to ftp.alpcom.it, inside the /software/mac/LMontalcini directory. The complete ShareDisk package, which contains all my stuff and can be registered at a very low price, is also available there.
◊ All online services and bulletin boards may make it available to their users at no charge other than the normal connection fees.
◊ All non-profit user groups may distribute it at no charge.
◊ All magazines may publish it on floppy disk without asking me first, as long as I get a copy of the issue containing my software.
◊ All CD-ROM shareware collections and CD-ROM magazines may include it without my prior consent, as long as I get either a copy of the CD-ROM or an offer to buy the CD-ROM at a discounted price.
◊ All redistribution companies such as Educorp may distribute it, as long as I get a copy of each media containing my software and a catalog of the company’s offerings (where applicable).
• Version history
◊ 1.2.1 - Fixed a problem with the Type and Key extensions, which added unwanted modifiers to some keys (especially number and arrow keys) on various keyboard configurations. Fixed the Menu extension to work with MenuChoice and other menu-related extensions that build their menus on the fly when the user clicks on the menu bar. The ChangeClip extension now correctly handles "\\" substitutions and accepts hexadecimal ASCII codes in the text. Fixed a couple of potential bugs in the control panel, which could cause problems when opening it and when importing macros. Added more third-party extensions, some third-party documentation and a link for Chris Johnson’s Cron timer.
◊ 1.2 - The Macro Editor can send KeyQuencer macros to remote Macs over a network; it also has a new option that prevents it from building the Extensions menu right away, which makes it a lot faster to launch. The new special cmd-shift-opt-return keystroke turns KeyQuencer on and off on the fly. Open and Quit don’t require KQ Apple Events any longer, even though they still use it when it’s installed. The Open extension can launch applications directly, including invisible applications, the File Sharing Extension and KQ Apple Events itself; it also brings up a file selection dialog if no file is specified. The new Drag extension handles mouse drags. The OMOpen extension cooperates with Jim Walker’s great OtherMenu system extension and lets you open files, folders, scripts and OtherMenu extensions from a KeyQuencer macro (OMOpen requires KQ Apple Events). The Confirm extension can be used to wait for a user confirmation before executing a macro. The WaitModifiers extension can pause a macro until some modifier keys are pressed or released. The Click extension can simulate double-clicks. WaitApp can wait for invisible background processes to be open or closed. KQ Apple Events is now very stable (there was a problem with old versions of the StuffIt Engine) and its memory requirements have been lowered to 16K; it also has a work-around for applications that don’t quit properly. Many extensions have a new "continue" parameter that prevents the macro from stopping after an error has occurred, some have a new "ask" parameter that allows data to be entered at runtime. All the window-related extensions have been updated to ignore floating palettes and the desktop. Key and Type now support all of the extended keyboard’s keys, and so does the Macro Editor. The control panel’s edit macro dialog no longer uses the clipboard to insert extension and parameter names in the macro. The developer’s toolkit includes a working Code Warrior project, and the code has been updated to allow global storage in both Think C and Code Warrior. Note that the the headers have changed, so old extensions have to be recompiled in order to work properly. There is a new folder with some excellent extensions created by Fabrizio Oddone and Jim Walker; these include AtStartup, Unmount, UnmountFO, ChoosePrinter, Shutdown and an alternative BalloonHelp extension. And finally, David Lewis wrote a handy new link for Frontier users.
◊ 1.11 - Fixed a problem with KQ Apple Events (Open and Quit could crash when KQ Apple Events quit unexpectedly). Added the new SelectWindow extension. Added the “mouse” parameter to the Click extension.
◊ 1.1 - This is a major new release. The Macro Editor application was added, along with lots of new extensions like PopUpMenu, Dial, ButtonList, Clipboard and Counter. All the old extensions have been updated (check out the new, smarter Open) and some of them accept new parameters. The “partial” keyword now really checks for partial matches. The Macro Editor, the Open extension and KQ Apple Events can execute macros contained in text files. Cmd-return can be used instead of enter in the control panel’s edit macro dialog. The Type command doesn’t use the keypad to type numbers any longer, so it doesn’t interfere with applications that have special keypad functions. The HyperCard link has a new XFCN that allows you to wait until KeyQuencer has done its work. There’s a new FileMaker Pro link that shows how to integrate KeyQuencer macros in your databases. A new developer’s toolkit allows programmers to write their own KeyQuencer extensions. And- yes, this documentation is now saved as styled text.
◊ 1.01 - Fixed a small bug in the macro editor dialog and added a work-around for WorldScript II. The Click extension now handles the closebox and zoombox better.
◊ 1.0 - First public release (after more than 30 beta versions).
• Credits
◊ The extensions in the “Third-party” folder were created by James Walker (walkerj@math.scarolina.edu), Fabrizio Oddone (gspnx@di.unito.it) and Didier Cabuzel (cabuzel_d@syseca.fr). Jim, Fabrizio and Didier kindly gave me permission to distribute these extensions as part of the KeyQuencer package, with no extra charge for you.
◊ The documentation in the “Third-party” folder was created by Ansel Webb, Henry Linton and Judy Engelsberg.
◊ The Frontier link was created by David Lewis.
• Thanks to…
◊ Lots of help and suggestions came from Valentina Pavia, Alberto Ricci, Fabrizio Oddone, Rocco Moliterno, Giovanni Rava, Alberto Novelli, Peppino Ventura, Massimo Lucano, Amedeo Farello, Giuseppe Carlino, Giorgio Berta, Luciano Baesso, Filippo Bellotti and Roberto Leonardi.
◊ Many people helped testing and improving KeyQuencer after its first release; special thanks to Masatsugu Nagata, Jim Walker, Leonard Rosenthol, Jon Gotow, Peter Lewis, Martin Charest, Joe Kissell, Michael Proctor, David Lewis, Dennis Little, Paul Bissex, Didier Cabuzel, Karl Jenkinson, Keith Corwin, David Collett and Scott Pendleton.
◊ KeyQuencer would certainly be a commercial product if I hadn’t received such a rewarding support from those who registered for my other shareware programs. I’d like to thank all my registered users one by one, but they are now way too many to list.
• Disclaimer
◊ KeyQuencer shouldn’t cause any damage, but you’re using it at your own risk. As an independent software developer, I can make no warranties whatsoever on it.
• Have fun!
◊ And don't forget to register your copy of KeyQuencer. I worked hard for many months to make it powerful and solid, yet I’m keeping the price very low so that everyone can afford it. If you’re starving, read the first paragraph again and see what else you can do to keep KeyQuencer alive.
